<!doctype html>
<html>
    <head>
        <title>HT for Web 工具条组件手册</title>
        <meta charset="UTF-8">    
        <meta name="viewport" content="user-scalable=yes, width=1024">
        <style type="text/css"> 
            h1, h2, h3, h4, h5, h6, p, blockquote {
                margin: 0;
                padding: 0;
            }
            body {
                font-family: "Helvetica Neue", Helvetica, "Hiragino Sans GB", Arial, sans-serif;
                font-size: 13px;
                line-height: 18px;
                color: #737373;
                background-color: white; 
                margin: 10px 13px 10px 13px;
            }
            table {
                margin: 10px 0 15px 0;
                border-collapse: collapse;
            }
            td,th {	
                border: 1px solid #ddd;
                padding: 3px 10px;
            }
            th {
                padding: 5px 10px;	
            }
            a {
                color: #0069d6;
            }
            a:hover {
                color: #0050a3;
                text-decoration: none;
            }
            a img {
                border: none;
            }
            p {
                margin-bottom: 9px;
            }
            h1, h2, h3, h4, h5, h6 {
                color: #404040;
                line-height: 36px;
            }
            h1 {
                margin-bottom: 18px;
                font-size: 30px;
            }
            h2 {
                font-size: 24px;
            }
            h3 {
                font-size: 18px;
            }
            h4 {
                font-size: 16px;
            }
            h5 {
                font-size: 14px;
            }
            h6 {
                font-size: 13px;
            }
            hr {
                margin: 0 0 19px;
                border: 0;
                border-bottom: 1px solid #ccc;
            }
            blockquote {
                padding: 13px 13px 21px 15px;
                margin-bottom: 18px;
                font-family:georgia,serif;
                font-style: italic;
            }
            blockquote:before {
                content:"\201C";
                font-size:40px;
                margin-left:-10px;
                font-family:georgia,serif;
                color:#eee;
            }
            blockquote p {
                font-size: 14px;
                font-weight: 300;
                line-height: 18px;
                margin-bottom: 0;
                font-style: italic;
            }
            code, pre {
                font-family: Monaco, Andale Mono, Courier New, monospace;
            }
            code {
                background-color: #fee9cc;
                color: rgba(0, 0, 0, 0.75);
                padding: 1px 3px;
                font-size: 12px;
                -webkit-border-radius: 3px;
                -moz-border-radius: 3px;
                border-radius: 3px;
            }
            pre {
                display: block;
                padding: 14px;
                margin: 0 0 18px;
                line-height: 16px;
                font-size: 11px;
                border: 1px solid #d9d9d9;
                white-space: pre-wrap;
                word-wrap: break-word;
            }
            pre code {
                background-color: #fff;
                color:#737373;
                font-size: 11px;
                padding: 0;
            }
            sup {
                font-size: 0.83em;
                vertical-align: super;
                line-height: 0;
            }
            * {
                -webkit-print-color-adjust: exact;
            }
            @media screen and (min-width: 914px) {
                body {
                    width: 854px;
                    margin:10px auto;
                }
            }
            @media print {
                body,code,pre code,h1,h2,h3,h4,h5,h6 {
                    color: black;
                }
                table, pre {
                    page-break-inside: avoid;
                }
            }                        
            iframe{
                width: 100%;
                border: 1px solid #34495E;
                margin: 0;                
            }            
            .logo{
                vertical-align: middle;
            }

        </style>        
        <script>
            function init() {
                var logoSrc = '',
                    logos = document.querySelectorAll('.logo'),
                    i = 0;
                for (; i < logos.length; i++) {
                    logos[i].src = logoSrc;
                }
                
                var iframes = document.querySelectorAll('iframe'),
                    func = function(){};
                for (i=0; i < iframes.length; i++) {
                    var iframe = iframes[i];
                    
                    // a small hack to make it work on android
                    iframe.ontouchstart = func;
                    
                    var div = document.createElement('div');
                    div.innerHTML = '<a href="' + iframe.src + '" target="_blank">独立运行→</a>';
                    iframe.parentNode.insertBefore(div, iframe);
                }   
            }
        </script>    
    </head>
    <body onload="init();">
        <a href="http://www.hightopo.com"><img class="logo"></a>HT for Web 工具条组件手册
        <hr style="margin: 1px 0 20px 0">
<p>索引</p>

<ul><li><a href="#ref_overview">概述</a></li><li><a href="#ref_basic">基础</a></li><li><a href="#ref_native">原生组件</a></li><li><a href="#ref_form">表单组件</a></li></ul>

<hr/>

<div id="ref_overview"></div>

<h2>概述</h2>

<p><code>HT for Web</code>提供了工具条组件类<code>ht.widget.Toolbar</code>，工具条上的元素可为原生的<code>html</code>元素，
也支持<code>ht</code>提供的如<code>ht-form.js</code>的表单插件中的组件，并内置提供了按钮、单选按钮、复选框等组件。</p>

<p>工具条支持水平<code>pan</code>的手抓图方式平移，当用户点击在原生或表单插件的组件时工具条不再进行交互控制，
当用户点击在内置组件时，如果后续有水平移动工具条会进行平移的手抓图效果操作，如果放手前没平移则
工具条会进行内置组件的点击操作，因此如果工具条元素较多需要平移功能时，建议尽量使用工具条内置组件，
一方面有助于更多空间可进行平移，另外内置组件占用内存资源也较少，有助于系统性能。</p>

<div id="ref_basic"></div>

<h2>基础</h2>

<p>通过<code>toolbar = new ht.widget.Toolbar(items);</code>初始化构建一个工具条对象，<code>items</code>参数为数组类型，
数组中的每个对象都会生成一个工具条元素(按钮、分隔条、原生<code>html</code>或表单插件组件)。</p>

<p>工具条主要可配置属性和函数如下：</p>

<ul><li><code>getItems()</code>和<code>setItems(items)</code>获取和设置工具条元素数组</li><li><code>itemGap</code>属性通过<code>getItemGap</code>和<code>setItemGap</code>获取和设置元素之间的间距</li><li><code>separatorColor</code>属性通过<code>getSeparatorColor</code>和<code>setSeparatorColor</code>获取和设置分隔条颜色</li><li><code>stickToRight</code>属性通过<code>isStickToRight</code>和<code>setStickToRight</code>获取和设置工具条是否向右对齐排布，默认为<code>false</code></li><li>通过<code>addItem(item, index)</code>可在指定<code>index</code>位置插入新元素，<code>index</code>为空代表插入到最后</li><li>通过<code>removeItem(item)</code>可删除指定元素</li><li>通过<code>removeItemById(id)</code>可删除指定编号<code>id</code>的元素，<code>id</code>值为<code>item</code>元素上的<code>id</code>属性定义</li><li>通过<code>getItemById(id)</code>可获取指定编号<code>id</code>的元素，<code>id</code>值为<code>item</code>元素上的<code>id</code>属性定义</li><li>通过重载<code>drawItem(g, item, x, height)</code>可自定义元素的绘制，函数返回该元素所占的宽度值</li><li>通过重载<code>getLabelFont(item)</code>可自定义文本字体</li><li>通过重载<code>getLabelColor(item)</code>可自定义文本颜色</li><li>通过重载<code>getSelectBackground(item)</code>可自定义选中背景颜色</li><li><code>redraw()</code>函数可用于<code>item</code>元素有所变化时进行刷新绘制   </li><li><code>enableToolTip()</code>和<code>disableToolTip()</code>开启和关闭文字提示</li><li><code>isDisabled()</code>和<code>setDisabled(true/false, iconURL)</code>可获取和设置整个组件处于不可用状态</li><li><code>getValue(id)</code>根据<code>id</code>获取对应<code>item</code>元素值，简写函数为<code>v(id)</code></li><li><p><code>setValue(id, value)</code>根据<code>id</code>设置对应<code>item</code>元素值，简写函数为<code>v(id, value)</code></p></li><li><p>数组中的<code>item</code>元素格式说明：</p><ul><li><code>separator</code>字符串，表示分隔条</li><li>对象类型<ul><li><code>id</code> 工具条元素的唯一标示，如果设置可通过<code>getItemById</code>获取</li><li><code>label</code> 工具条元素的标签文字。</li><li><code>icon</code> 工具条元素的图标。</li><li><code>toolTip</code> 工具条元素的文字提示，注意需要结合<code>Toolbar#enableToolTip()</code></li><li><code>type</code> 工具条元素类型，<code>check</code>表示复选框，<code>toggle</code>表示开关按钮，<code>radio</code>表示单选按钮</li><li><code>selected</code> 工具条元素是否被选中，值为<code>true</code>或<code>false</code>，对复选框、开关按钮和单选按钮有效</li><li><code>visible</code> 工具条元素是否可见，默认值为<code>true</code>，设置为<code>false</code>则隐藏该元素</li><li><code>unfocusable</code> 工具条元素是否不可获取焦点，默认鼠标滑过时会显示一个矩形边框，可设置为<code>true</code>关闭此效果</li><li><code>disabled</code> 工具条元素是否被禁用，默认值为<code>false</code></li><li><code>groupId</code> 对工具条元素进行分组，同一个分组内的元素选中会自动出现互斥效果</li><li><code>element</code> 可在该属性上直接设置元素<code>html</code>或表单组件元素</li><li><code>width</code> 工具条元素宽度，常和<code>element</code>搭配使用，工具条内置组件无需设置该值</li><li><code>action</code> 函数类型，工具条元素被点击时调用。</li></ul></li></ul></li></ul>

<p><iframe src="examples/example_basic.html" style="height:120px"></iframe></p>

<div id="ref_native"></div>

<h2>原生组件</h2>

<p>内置的组件以及下节介绍的表单组件已经能满足大部分应用需求，但工具条依然允许用户放置原生的<code>html</code>组件，
例如元素的<code>select</code>下拉组件，或者用户已经封装好的<code>html</code>组件，对于所有组件工具条都会将其<code>css</code>的
<code>position</code>属性设置为<code>absolute</code>，<code>box-sizing</code>属性设置为<code>border-box</code>的方式进行绝对定位的布局。</p>

<p>采用<code>native</code>的元素组件在配置时，只需要在<code>item</code>的配置属性<code>element</code>上设置上<code>html</code>元素对象即可，
另外需注意<code>item</code>的<code>action</code>属性不会起作用，如果要监听组件的事件变化，用户需自行对<code>html</code>元素添加原生的监听事件。</p>

<p><iframe src="examples/example_native.html" style="height:120px"></iframe></p>

<div id="ref_form"></div>

<h2>表单组件</h2>

<p>对于<a href="../../plugin/form/ht-form-guide.html">表单插件</a>提供的组件也都可设置在<code>item</code>的<code>element</code>属性上，
并且工具条还支持用<code>json</code>直接描述自动构建<code>element</code>元素的机制。</p>

<p>如下代码将构建通过关键字属性<code>slider</code>，自动构建<code>ht.widget.Slider</code>组件，并将该组件自动存储到<code>item</code>的<code>element</code>属性上，
<code>ht</code>内部先以不带参数的构造函数构造出组件对象，然后根据<code>json</code>上配置的属性信息查找是否有对应的<code>set</code>函数，
如果有对应的<code>set</code>函数则直接赋值到该对象，如果没找到对应函数则直接用将该属性名和值设置到对象上。</p>

<pre><code>var toolbar = new ht.widget.Toolbar([
    {
        id: &#39;step&#39;,
        label: &#39;Step&#39;,
        unfocusable: true,
        slider: {
            width: 120,
            step: 5,
            min: 100,
            max: 200,
            value: 125,
            thickness: 1,
            onValueChanged: function(){
                toolbar.getItemById(&#39;step&#39;).label = this.getValue();
                toolbar.redraw();
            },
            onEndValueChanged: function(){
                toolbar.getItemById(&#39;step&#39;).label = &#39;Step&#39;;
                toolbar.redraw();
            }        
        }
    }
]);</code></pre>

<p>以下代码为<code>slider</code>对象构建的过程：</p>

<pre><code>slider = new ht.widget.Slider();
item.element = slider;
slider.setWidth(120);
slider.setStep(5);
slider.setMin(100);
slider.setMax(200);
slider.setValue(125);
slider.setThickness(1);
slider.onValueChanged = function(){
    toolbar.getItemById(&#39;step&#39;).label = this.getValue();
    toolbar.redraw();
};
slider.onEndValueChanged: function(){
    toolbar.getItemById(&#39;step&#39;).label = &#39;Step&#39;;
    toolbar.redraw();
};    </code></pre>

<p>以下为<code>ht</code>目前支持的几个组件关键字映射关系：</p>

<ul><li><code>textField</code> -&gt; <code>ht.widget.TextField</code></li><li><code>textArea</code> -&gt; <code>ht.widget.TextArea</code></li><li><code>button</code> -&gt; <code>ht.widget.Button</code></li><li><code>checkBox</code> -&gt; <code>ht.widget.CheckBox</code></li><li><code>image</code> -&gt; <code>ht.widget.Image</code></li><li><code>comboBox</code> -&gt; <code>ht.widget.ComboBox</code></li><li><code>slider</code> -&gt; <code>ht.widget.Slider</code></li></ul>

<p><iframe src="examples/example_form.html" style="height:120px"></iframe></p>

<pre><code>function createToolbar(){
    var toolbar = new ht.widget.Toolbar([
        {
            id: &#39;step&#39;,
            label: &#39;Step&#39;,
            unfocusable: true,
            slider: {
                width: 120,
                step: 5,
                min: 100,
                max: 200,
                value: 125,
                thickness: 1,
                onValueChanged: function(){
                    toolbar.getItemById(&#39;step&#39;).label = this.getValue();
                    toolbar.redraw();
                },
                onEndValueChanged: function(){
                    toolbar.getItemById(&#39;step&#39;).label = &#39;Step&#39;;
                    toolbar.redraw();
                }        
            }
        },
        {        
            id: &#39;nation&#39;,
            label: &#39;Nation&#39;,                        
            unfocusable: true,
            comboBox: {
                width: 120,
                value: &#39;Sweden&#39;,
                values: [&#39;Spain&#39;, &#39;Sweden&#39;, &#39;Switzerland&#39;],
                icons: [&#39;images/spain.png&#39;, &#39;images/sweden.png&#39;, &#39;images/switzerland.png&#39;]
            }
        },
        {
            id: &#39;text&#39;,
            unfocusable: true,
            textField: {
                width: 120,
                color: &#39;red&#39;        
            }
        },
        &#39;separator&#39;, 
        {
            label: &#39;Get Information&#39;,
            action: function(){                            
                alert(&#39;Slider:&#39; + toolbar.v(&#39;step&#39;) + &#39;\n&#39; +
                    &#39;Nation:&#39; + toolbar.v(&#39;nation&#39;) + &#39;\n&#39; +
                    &#39;Name:&#39; + toolbar.v(&#39;text&#39;)
                );
            }
        }
    ]);
    toolbar.v(&#39;text&#39;, &#39;Eric Lin&#39;);
    return toolbar;                
}</code></pre>    <hr id="contact" style="margin: 20px 0 1px 0">
    <a href="http://www.hightopo.com"><img class="logo"></a>欢迎交流 <a href="mailto:service@hightopo.com">service@hightopo.com</a>
</body>
</html>
